Repository navigation
Feat: Respect naming conventions for autogenerated spatial indexes - #628
Open
adrien-berchet wants to merge 3 commits into
Open
adrien-berchet wants to merge 3 commits into
adrien-berchet wants to merge 3 commits into
Conversation
…eoalchemy#401) Add the `follow_naming_convention` parameter (default `False`) to `Geometry`, `Geography`, and `Raster` types to allow autogenerated spatial indexes to respect SQLAlchemy metadata naming conventions. - Mark autogenerated indexes with `info={"geoalchemy2_spatial_index": True}` rather than relying on name-based checks. - Resolve naming conventions from `MetaData.naming_convention["ix"]` with fallback to `idx_<table>_<column>` if no convention is set. - Respect explicit index names in MySQL DDL when enabled while maintaining unnamed `ADD SPATIAL INDEX(col)` when disabled. - Eliminate Alembic false diffs for SQLite/SpatiaLite and GeoPackage R-tree virtual tables via Alembic rewriters. - Update Alembic documentation and migration test suite.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #401.
This PR adds an opt-in parameter,
follow_naming_convention(defaultFalse), toGeometry,Geography, andRastertypes. When enabled, autogenerated spatial indexes follow the naming conventions defined on SQLAlchemy'sMetaData(naming_convention=...)instead of being hardcoded toidx_<tablename>_<columnname>.Context & Motivation
Previously, GeoAlchemy2 always generated spatial index names via the internal helper
_spatial_idx_name(table.name, column.name), which hardcoded the formatidx_<tablename>_<columnname>. This ignored any custom naming conventions configured onMetaData.naming_convention(or SQLAlchemy's default convention{"ix": "ix_%(column_0_label)s"}), causing inconsistency across schemas and false diffs during Alembic autogenerate migrations.Key Changes
1. Opt-In Parameter & Fallback Resolution
follow_naming_convention: bool = Falseto_GISType(Geometry,Geography) andRaster.follow_naming_convention=True, an unnamedIndex(None, ...)is appended to the table duringbefore_parent_attach, allowing SQLAlchemy to resolve the name againstMetaData.naming_convention["ix"]."ix"(orIndex) naming convention key, the index name safely falls back toidx_<tablename>_<columnname>.2. Marker-Based Index Identification
idx.name == _spatial_idx_name(...)) across all dialects with an internal marker:info={"geoalchemy2_spatial_index": True}(plus_column_flag=True).idx_<tablename>_<columnname>are no longer mistaken for autogenerated spatial indexes and will no longer have their options (e.g.postgresql_where) silently dropped.3. Dialect Support
use_typmod=True) generates convention-named GiST indexes during table creation.use_typmod=False) stores the convention name intable.info["_generated_spatial_indexes"]soafter_createcreates the index with the resolved name.ALTER TABLE <table> ADD SPATIAL INDEX <format_index>(<quoted_col>)whenfollow_naming_convention=True.ALTER TABLE <table> ADD SPATIAL INDEX(<quoted_col>)when disabled._monkey_patch_get_indexes_for_mysqlto only synthesizeidx_t_cwhenINDEX_NAME == COLUMN_NAME(MySQL's default unnamed index), avoiding duplicate index diffs in Alembic for explicitly named user spatial indexes.alter_geo_columnviatarget_metadata.idx_<table>_<column>) and GeoPackage R-tree tables (rtree_<table>_<column>) cannot be renamed due to C-extension requirements._filter_sqlite_spatial_index_opsviawriter) to filter out false drop/create diffs when comparing models with existing databases.4. Documentation & Migration Guide
doc/alembic.rstwith a detailed section on naming conventions, fallback rules, dialect specifics, and guidance on migrating existing databases.CHANGES.txt.Backward Compatibility
follow_naming_conventiondefaults toFalse, preserving exact previous index names (idx_<table>_<column>), DDL statements, and Alembic behavior.Verification & Testing
tests/test_admin_common.pytests/test_functional_postgresql.pytests/test_functional_mysql.pytests/test_functional_sqlite.pytests/test_functional_geopackage.pytests/test_functional_mssql.pytests/test_alembic_migrations.pypy312-sqlalatestandpy312-sqla14with required coverage reached (>= 89%).ruff check,ruff format) pass cleanly.